Cache

The Amplify Cache module provides a generic LRU cache for JavaScript developers to store data with priority and expiration settings.

It is a key/value structure where expiration values can be configured globally or on a per-key basis. For instance, you may wish to cache all JSON responses from the API module for the next 10 minutes, but like to store user input values or preferences for a month.

Installation

Install aws-amplify.

npm install aws-amplify

Working with the API

First, import the library:

import { Cache } from 'aws-amplify';

After the import, you can invoke the appropriate methods within your application.

setItem()

Cache.setItem(key, value, [options]);

You can set number, string, boolean or object values to the cache. You can also specify options along with the call such as the priority or expiration time.

// Standard case
Cache.setItem('key', 'value');

// Set item with priority. Priority should be between 1 and 5.
Cache.setItem('key', 'value', { priority: 3 });

// Set item with an expiration time
const expiration = new Date(2018, 1, 1);
Cache.setItem('key', 'value', { expires: expiration.getTime() });

When using priority setting, the cached item with the lower number will be expired first. The Cache module decides expiration based on the memory available to the cache. In the following example,breakfastFoodOrder will be expired before mothersBirthday.

Cache.setItem('mothersBirthday', 'July 18th', { priority: 1 });
Cache.setItem('breakfastFoodOrder', 'Pancakes', { priority: 3 });

getItem()

Cache.getItem(key[, options]);

Retrieves an item from the cache. It will return null if the item doesn’t exist or it has expired.

// Standard case
Cache.getItem('key');

// Get item with callback function.
// The callback function will be called if the item is not in the cache.
// After the callback function returns, the value will be set into cache.
Cache.getItem('key', { callback: callback });

removeItem()

Removes item from cache.

Cache.removeItem(key);

clear()

Removes all of the items in the cache.

Cache.clear();

getAllKeys()

Returns all of the keys available in the cache.

Cache.getAllKeys();

getCacheCurSize()

Returns the current size of the cache in bytes.

const size = Cache.getCacheCurSize();

configure()

Configures default settings for setItem functionality. You can see all available options in Configuration section.

const config = {
  itemMaxSize: 3000, // 3000 bytes
  defaultPriority: 4
  // ...
};
const myCacheConfig = Cache.configure(config);

// You can modify parameters such as cache size, item default ttl and etc.
// But don't try to modify keyPrefix which is the identifier of Cache.

createInstance()

Creates a new instance of Cache with custom configuration.

const config = {
  itemMaxSize: 3000, // 3000 bytes
  storage: window.sessionStorage // switch to sessionStorage
  // ...
};
const newCache = Cache.createInstance(config);
// Please provide a new keyPrefix which is the identifier of Cache.

API Reference

For the complete API documentation for Cache module, visit our API Reference

Configuration

Configuration Parameters

Here is the list of configuration parameters for the Cache module:

Configuration Parameters for Items

Here is the list of configuration parameters for the items in the cache :

Using Modular Imports

If you only need to use Cache, you can do: npm install @aws-amplify/cache which will only install the Cache module for you.

Then in your code, you can import the Cache module by:

import Cache from '@aws-amplify/cache';

Cache.configure();